fix(chat): keep steering, action and injected messages in the conversation - #4816

drainSteeringQueue used the injected uiMessage for span attributes, the
injection-confirmation chunk, the injected-ids set and onInjected — never the
accumulator. So the message reached the model and the browser, appeared in
neither uiMessages nor newUIMessages, and an app persisting from onTurnComplete
never learned it existed. The user steers, the agent obeys, the user reloads, and
their instruction is gone from the transcript and from every later turn's
context.

The asymmetry is the tell: a message that finds no step boundary falls back to
becoming its own turn and is accumulated normally. Only the path that worked lost
data.

Appended at injection time rather than turn end, so the order matches what
happened: after the message that started the turn, before the response that
answers it. Deduplicated by id, since a boundary can drain more than once.

The injection path had no test coverage at all — shouldInject appeared only in
ai.ts — because the harness had no way to deliver a message mid-turn. Adds
harness.sendPendingMessage() for that, which is also what a customer needs to
test steering in their own suite.

The snapshot is written on the turn-complete path, and an action is not a turn —
the block literally ends 'if (!isAction)'. So a chat.history mutation from
onAction lived only in the running worker's memory. Undo worked while that worker
stayed warm, then the next continuation booted from a snapshot still holding the
undone exchange and the messages came back. onAction is exactly where the docs
tell you to call rollbackTo, so this is the documented path silently not
persisting.

Writes the snapshot right after the action's override is applied, awaited for the
same reason as the turn-complete write: the agent may suspend straight after, and
in-flight promises do not reliably survive that.

An action has no turn cursor, so the write reuses the last one rather than
writing undefined — that would drop the resume point and make the next boot
replay from further back to rebuild what it could have read.

…ation

Returning a StreamTextResult from onAction piped it to the browser and stopped
there. The accumulator never saw it, no snapshot recorded it, and actions fire no
onTurnComplete — so the user read a good answer that the model had no memory of,
and the next turn carried on from the answer regenerate had just replaced. The
disagreement between the screen and the conversation was invisible until that
next turn contradicted it.

The action branch now captures what it pipes, using the pipeChatAndCapture that
already existed for exactly this, and appends the message to the accumulator.
Persistence beyond the snapshot is still the app's job, since an action fires no
turn hook — pipeAndCapture hands back the same message for that.

Also folds the snapshot write added for rolled-back history into one helper used
by both action paths, so a regenerate that both rolls back and answers writes
once rather than twice, and the cursor-preservation rule lives in one place.

The two fixes needed each other: with the rollback persisted but the response
dropped, a regenerate left the snapshot empty rather than stale — still wrong,
just differently.

chat.inject with role 'system' put the message into the conversation, which ai@7
rejects for every provider: standardizePrompt throws before any provider is
called. The next turn died with an error chunk reading 'An error occurred.' and
persisted an assistant message with no parts, so from the app's side the agent
had simply stopped answering.

The error message names the fix — use the instructions option — and Instructions
is string | SystemModelMessage | Array<SystemModelMessage>, so an injected system
block has a correct home. It is appended after the base prompt, which keeps the
prompt's position for caching and reads as a later amendment.

This makes the documented examples right rather than rewriting them to a
workaround. It also answers whether trusted mid-conversation context is
supportable: it is, and only this way. A message injected as 'user' is untrusted
by construction, and a well-aligned model says so and re-derives the answer from
tools instead. The docs now state which lane to use for facts and which for
directives.

A new instruction block changes the cached prefix, so the first call carrying it
misses the prompt cache. Only turns that actually injected pay it.

… paths

Record only the messages a steering drain actually claimed. The loop used the
offered batch, so a record another consumer took while shouldInject() awaited
was written into the accumulator for a turn it was never part of.

Drain the injected instructions once applied, matching the conversational
lane. Left in place they were re-applied by every later toStreamTextOptions()
call in the run, growing the prompt and changing its cached prefix each turn.

Clean a stopped action's partial response before it is committed, and skip
committing at all once the run is cancelled.

…finished

pipeChatAndCapture returns a stream failure rather than throwing it, so a
mid-stream failure in a response returned from onAction was committed as a
complete answer, snapshotted, and followed by a normal turn-complete with no
error — the browser saw the stream stop and the next turn built on the
truncated text. The partial is still kept; the failure is now surfaced with it.

Document that the instructions lane is delivered by chat.toStreamTextOptions(),
and that an injection applies to the next inference call only.

The actions page said only that persistence was your responsibility inside
onAction, which is now wrong for platform-managed agents (the runtime writes
the snapshot) and too vague for app-owned ones, where a rollback and a
streamed replacement both need storing and there is no onTurnComplete to do
it in.

Drops the banned trivializing words, replaces future tense and "there is"
throat-clearing, and removes a "two things" lead-in that sat above three
bullets. Merges the two bullets that stated the same prompt-cache fact, and
stops claiming the injected block is appended as an array when it is merged
into a single instruction.

Recast each one as a comma, colon, parentheses, or two sentences rather than
swapping in a hyphen. Also removes a stray "simply", a future tense, and a
"had just been replaced" the previous pass missed in the changesets.

…ction pages

Covers the prose these pages already had, not only the new sections: the
frontmatter descriptions, code comments, the message-role table cell, the
injection-point list, and the see-also link descriptions. Each recast as a
colon, comma, parentheses, or two sentences.

Both stay patch. The double write only bites code that worked around a lost
message, and the silent action completion was the bug it now reports, so
neither is new functionality or an API break. The version cannot carry either
signal, so the changelog entries name them instead.

Also documents sendPendingMessage in the testing harness table, which listed
every other send method.

Draining the lane on read handed the injection to whichever
chat.toStreamTextOptions() call ran first and dropped it from the rest. A
run() that builds options twice, a classifier pass and then the answer, sent
the instruction to nobody if it passed the second one to streamText, with no
error anywhere. Consumption is now keyed on the turn, so every build in the
turn carries the same instructions and the turn after it carries none. A
hand-rolled loop with no turn context still drains on read.

drainSteeringQueue reported what it claimed by pushing into a locals
array that only chat.agent populates, so on chat.createSession and
chat.MessageAccumulator the push was a silent no-op behind its
truthiness guard. A mid-turn steer shaped that turn's answer and then
existed nowhere: not in the session's uiMessages, not in its
modelMessages, and not deferred to its own turn either.

The drain now returns what it claimed alongside what to inject, and each
surface files it. Adds absorbSteering to the accumulator, used by both
of its drain sites.

The error path built newUIMessages from the wire message and the partial
only, never from the per-turn list the drain appends to, so a turn that
failed after a steer handed onTurnComplete everything except the steer.
Seeded from the per-turn list at both construction sites, deduped by id.
Reproduced with a stream that rejects mid-answer; an AI SDK error part
takes the normal completion path and was never affected.

An action and the message after it share a turn number, so the action
reads the pending instruction and the intended turn still receives it,
and it does not carry to the turn after. Removing the per-turn stash
makes the action consume it and the intended turn gets nothing, which
is the failure the stash prevents.